The DataSourceProvider class allows Xceed's listbox controls to support a wide range of data sources. The main purpose of this class is to translate requests from the component into queries to be processed by the data source. The data-source providers can be classified into two distinct categories: synchronous and asynchronous. A data-source provider is considered synchronous if all calls or requests made on it return synchronously.  All other cases are considered asynchronous.

Although a variety of data-source providers are built into Xceed's listbox controls (see Table 1) and attempts are made to automatically detect the appropriate one to use when binding the listbox to a data source, in some cases, it might be necessary to explicitly define which data-source provider to use or to create your own.

Table 1: Built-in data-source providers

Custom Data-Source Providers

In some cases, the built-in data-source providers will not be compatible with the targeted data source. In this situation, a custom data-source provider can be created by deriving from one of the following classes:

Provider	Description
AsyncDataSourceProvider	One of the most primitive providers that can be used with an asynchronous data source.
AsyncIndexDataSourceProvider	Ideal for an asynchronous data source that can easily access items from an index or that cannot filter items efficiently.
AsyncSqlDataSourceProvider	Ideal for an asynchronous SQL data source. The generated queries can  easily be converted into SQL-like queries. If the query is used in whole or in part for dynamic SQL, it must first be validated to avoid SQL injection security breaches.
SimpleAsyncIndexDataSourceProvider	Simplified version of the AsyncIndexDataSourceProvider.
SimpleSyncIndexDataSourceProvider	Simplified version of the SyncIndexDataSourceProvider.
SyncDataSourceProvider	One of the most primitive providers that can be used with a synchronous data source.
SyncIndexDataSourceProvider	Ideal for a synchronous data source that can easily access items from an index or that cannot filter items efficiently.
WcfDataServicesDataSourceProviderBase	Ideal for a WCF Data Services data source if the built-in WcfDataServicesDataSourceProvider does not provide all the desired functionality. If the data source is a DataServiceQuery<>, WcfDataServicesDataSourceProvider<> should be used instead.
WcfDataServicesDataSourceProviderBase<>	Ideal for WCF Data Services data source if the built-in WcfDataServicesDataSourceProvider<> does not provide all the desired functionality.

All data-source providers must provide required information. For example,  the ElementType property must return the type of the elements contained in the data source.  Only columns that are bound to a property or a field found on this type can be grouped, sorted, or filtered.

In order to target an element precisely, each element must be unique. The GetPrimaryKeyInfo method must be overridden by your data-source provider and return the list of properties or fields that identify an element as being unique.

To change the filter operators and statistical functions that are supported by a data-source provider, the GetSupportedFilterOperators and GetSupportedStatFunctions methods must be overridden and return the modified list of filter operators and statistical functions.

Depending on the base class being used, it may be necessary to override some of the methods that deal with a precise type of query such as a count query, which requests the number of elements, the data query, which requests the elements themselves, the find query, which requests a position, the group-count query, which requests the number of groups per level, or the stat query, which requests the result of a statistical function. All queries are applied on a range.

Queries may be enabled or disabled via their associated CanCount, CanFind, CanGroupCount, and CanCalculateStats properties. It is not necessary of a data-source provider to support all queries.

Processing Queries

In some cases, a method that handles a query in order to retrieve information from the data source will be called. Your role as an implementer is for query your data source according to the provided criteria.  Each criterion has a specific purpose: 

Request	Description
FilterGroupRequest	Keep only the elements of a target group.
FilterRequest	Keep only the elements that match the predicate.
FindRequest	Retrieve the position of an element.
ItemJumpRequest	Start retrieval from a target element.
JumpRequest	Start retrieval from a target position.
SkipRequest	Skip a number of elements.
SortRequest	Sort the elements.
TakeRequest	Take a number of elements.

Some of the criteria are mutually exclusive and may not be specified on every query.  If specified, here is the order in which the criteria must be applied in order to return the expected result:

1. FilterRequest, FilterGroupRequest, SortRequest
2. ItemJumpRequest, JumpRequest
3. SkipRequest
4. FindRequest, TakeRequest

Criteria may be enabled or disabled via their associated CanFilterGroup, CanFilter, CanFind, CanJumpToItem, CanJump, and CanSkip properties. It is not necessary for a data-source provider to support all criteria.